home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / savedstatuses.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  13.2 KB  |  417 lines
  1. /**
  2.  * @file savedstatuses.h Saved Status API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _PURPLE_SAVEDSTATUSES_H_
  26. #define _PURPLE_SAVEDSTATUSES_H_
  27.  
  28. /**
  29.  * Saved statuses don't really interact much with the rest of Purple.  It
  30.  * could really be a plugin.  It's just a list of away states.  When
  31.  * a user chooses one of the saved states, their Purple accounts are set
  32.  * to the settings of that state.
  33.  *
  34.  * In the savedstatus API, there is the concept of a 'transient'
  35.  * saved status.  A transient saved status is one that is not
  36.  * permanent.  Purple will removed it automatically if it isn't
  37.  * used for a period of time.  Transient saved statuses don't
  38.  * have titles and they don't show up in the list of saved
  39.  * statuses.  In fact, if a saved status does not have a title
  40.  * then it is transient.  If it does have a title, then it is not
  41.  * transient.
  42.  *
  43.  * What good is a transient status, you ask?  They can be used to
  44.  * keep track of the user's 5 most recently used statuses, for
  45.  * example.  Basically if they just set a message on the fly,
  46.  * we'll cache it for them in case they want to use it again.  If
  47.  * they don't use it again, we'll just delete it.
  48.  */
  49.  
  50. /*
  51.  * TODO: Hmm.  We should probably just be saving PurplePresences.  That's
  52.  *       something we should look into once the status box gets fleshed
  53.  *       out more.
  54.  */
  55.  
  56. typedef struct _PurpleSavedStatus     PurpleSavedStatus;
  57. typedef struct _PurpleSavedStatusSub  PurpleSavedStatusSub;
  58.  
  59. #include "status.h"
  60.  
  61. #ifdef __cplusplus
  62. extern "C" {
  63. #endif
  64.  
  65. /**************************************************************************/
  66. /** @name Saved status subsystem                                          */
  67. /**************************************************************************/
  68. /*@{*/
  69.  
  70. /**
  71.  * Create a new saved status.  This will add the saved status to the
  72.  * list of saved statuses and writes the revised list to status.xml.
  73.  *
  74.  * @param title     The title of the saved status.  This must be
  75.  *                  unique.  Or, if you want to create a transient
  76.  *                  saved status, then pass in NULL.
  77.  * @param type      The type of saved status.
  78.  *
  79.  * @return The newly created saved status, or NULL if the title you
  80.  *         used was already taken.
  81.  */
  82. PurpleSavedStatus *purple_savedstatus_new(const char *title,
  83.                                       PurpleStatusPrimitive type);
  84.  
  85. /**
  86.  * Set the title for the given saved status.
  87.  *
  88.  * @param status  The saved status.
  89.  * @param title   The title of the saved status.
  90.  */
  91. void purple_savedstatus_set_title(PurpleSavedStatus *status,
  92.                                 const char *title);
  93.  
  94. /**
  95.  * Set the type for the given saved status.
  96.  *
  97.  * @param status  The saved status.
  98.  * @param type    The type of saved status.
  99.  */
  100. void purple_savedstatus_set_type(PurpleSavedStatus *status,
  101.                                PurpleStatusPrimitive type);
  102.  
  103. /**
  104.  * Set the message for the given saved status.
  105.  *
  106.  * @param status  The saved status.
  107.  * @param message The message, or NULL if you want to unset the
  108.  *                message for this status.
  109.  */
  110. void purple_savedstatus_set_message(PurpleSavedStatus *status,
  111.                                   const char *message);
  112.  
  113. /**
  114.  * Set a substatus for an account in a saved status.
  115.  *
  116.  * @param status    The saved status.
  117.  * @param account    The account.
  118.  * @param type        The status type for the account in the staved
  119.  *                  status.
  120.  * @param message    The message for the account in the substatus.
  121.  */
  122. void purple_savedstatus_set_substatus(PurpleSavedStatus *status,
  123.                                     const PurpleAccount *account,
  124.                                     const PurpleStatusType *type,
  125.                                     const char *message);
  126.  
  127. /**
  128.  * Unset a substatus for an account in a saved status.  This clears
  129.  * the previosly set substatus for the PurpleSavedStatus.  If this
  130.  * saved status is activated then this account will use the default
  131.  * status type and message.
  132.  *
  133.  * @param saved_status The saved status.
  134.  * @param account      The account.
  135. */
  136. void purple_savedstatus_unset_substatus(PurpleSavedStatus *saved_status,
  137.                                                   const PurpleAccount *account);
  138.  
  139. /**
  140.  * Delete a saved status.  This removes the saved status from the list
  141.  * of saved statuses, and writes the revised list to status.xml.
  142.  *
  143.  * @param title The title of the saved status.
  144.  *
  145.  * @return TRUE if the status was successfully deleted.  FALSE if the
  146.  *         status could not be deleted because no saved status exists
  147.  *         with the given title.
  148.  */
  149. gboolean purple_savedstatus_delete(const char *title);
  150.  
  151. /**
  152.  * Returns all saved statuses.
  153.  *
  154.  * @return A list of saved statuses.
  155.  */
  156. const GList *purple_savedstatuses_get_all(void);
  157.  
  158. /**
  159.  * Returns the n most popular saved statuses.  "Popularity" is
  160.  * determined by when the last time a saved_status was used and
  161.  * how many times it has been used.  If the current status would
  162.  * normally show up in this list, then it is omited and instead
  163.  * the "how_many+1" saved status will appear in the list.  Also
  164.  * transient statuses without messages are not included in the
  165.  * list.
  166.  *
  167.  * @param how_many The maximum number of saved statuses
  168.  *                 to return, or '0' to get all saved
  169.  *                 statuses sorted by popularity.
  170.  * @return A linked list containing at most how_many
  171.  *         PurpleSavedStatuses.  This list should be
  172.  *         g_list_free'd by the caller (but the
  173.  *         PurpleSavedStatuses must not be free'd).
  174.  */
  175. GList *purple_savedstatuses_get_popular(unsigned int how_many);
  176.  
  177. /**
  178.  * Returns the currently selected saved status.  If we are idle
  179.  * then this returns purple_savedstatus_get_idleaway().  Otherwise
  180.  * it returns purple_savedstatus_get_default().
  181.  *
  182.  * @return A pointer to the in-use PurpleSavedStatus.
  183.  *         This function never returns NULL.
  184.  */
  185. PurpleSavedStatus *purple_savedstatus_get_current(void);
  186.  
  187. /**
  188.  * Returns the default saved status that is used when our
  189.  * accounts are not idle-away.
  190.  *
  191.  * @return A pointer to the in-use PurpleSavedStatus.
  192.  *         This function never returns NULL.
  193.  */
  194. PurpleSavedStatus *purple_savedstatus_get_default(void);
  195.  
  196. /**
  197.  * Returns the saved status that is used when your
  198.  * accounts become idle-away.
  199.  *
  200.  * @return A pointer to the idle-away PurpleSavedStatus.
  201.  *         This function never returns NULL.
  202.  */
  203. PurpleSavedStatus *purple_savedstatus_get_idleaway(void);
  204.  
  205. /**
  206.  * Return TRUE if we are currently idle-away.  Otherwise
  207.  * returns FALSE.
  208.  *
  209.  * @return TRUE if our accounts have been set to idle-away.
  210.  */
  211. gboolean purple_savedstatus_is_idleaway(void);
  212.  
  213. /**
  214.  * Set whether accounts in Purple are idle-away or not.
  215.  *
  216.  * @param idleaway TRUE if accounts should be switched to use the
  217.  *                 idle-away saved status.  FALSE if they should
  218.  *                 be switched to use the default status.
  219.  */
  220. void purple_savedstatus_set_idleaway(gboolean idleaway);
  221.  
  222. /**
  223.  * Returns the status to be used when purple is starting up
  224.  *
  225.  * @return A pointer to the startup PurpleSavedStatus.
  226.  *         This function never returns NULL.
  227.  */
  228. PurpleSavedStatus *purple_savedstatus_get_startup(void);
  229.  
  230. /**
  231.  * Finds a saved status with the specified title.
  232.  *
  233.  * @param title The name of the saved status.
  234.  *
  235.  * @return The saved status if found, or NULL.
  236.  */
  237. PurpleSavedStatus *purple_savedstatus_find(const char *title);
  238.  
  239. /**
  240.  * Finds a saved status with the specified creation time.
  241.  *
  242.  * @param creation_time The timestamp when the saved
  243.  *        status was created.
  244.  *
  245.  * @return The saved status if found, or NULL.
  246.  */
  247. PurpleSavedStatus *purple_savedstatus_find_by_creation_time(time_t creation_time);
  248.  
  249. /**
  250.  * Finds a saved status with the specified primitive and message.
  251.  *
  252.  * @param type The PurpleStatusPrimitive for the status you're trying
  253.  *        to find.
  254.  * @param message The message for the status you're trying
  255.  *        to find.
  256.  *
  257.  * @return The saved status if found, or NULL.
  258.  */
  259. PurpleSavedStatus *purple_savedstatus_find_transient_by_type_and_message(PurpleStatusPrimitive type, const char *message);
  260.  
  261. /**
  262.  * Determines if a given saved status is "transient."
  263.  * A transient saved status is one that was not
  264.  * explicitly added by the user.  Transient statuses
  265.  * are automatically removed if they are not used
  266.  * for a period of time.
  267.  *
  268.  * A transient saved statuses is automatically
  269.  * created by the status box when the user sets himself
  270.  * to one of the generic primitive statuses.  The reason
  271.  * we need to save this status information is so we can
  272.  * restore it when Purple restarts.
  273.  *
  274.  * @param saved_status The saved status.
  275.  *
  276.  * @return TRUE if the saved status is transient.
  277.  */
  278. gboolean purple_savedstatus_is_transient(const PurpleSavedStatus *saved_status);
  279.  
  280. /**
  281.  * Return the name of a given saved status.
  282.  *
  283.  * @param saved_status The saved status.
  284.  *
  285.  * @return The title.  This value may be a static buffer which may
  286.  *         be overwritten on subsequent calls to this function.  If
  287.  *         you need a reference to the title for prolonged use then
  288.  *         you should make a copy of it.
  289.  */
  290. const char *purple_savedstatus_get_title(const PurpleSavedStatus *saved_status);
  291.  
  292. /**
  293.  * Return the type of a given saved status.
  294.  *
  295.  * @param saved_status The saved status.
  296.  *
  297.  * @return The name.
  298.  */
  299. PurpleStatusPrimitive purple_savedstatus_get_type(const PurpleSavedStatus *saved_status);
  300.  
  301. /**
  302.  * Return the default message of a given saved status.
  303.  *
  304.  * @param saved_status The saved status.
  305.  *
  306.  * @return The message.  This will return NULL if the saved
  307.  *         status does not have a message.  This will
  308.  *         contain the normal markup that is created by
  309.  *         Purple's IMHTML (basically HTML markup).
  310.  */
  311. const char *purple_savedstatus_get_message(const PurpleSavedStatus *saved_status);
  312.  
  313. /**
  314.  * Return the time in seconds-since-the-epoch when this
  315.  * saved status was created.  Note: For any status created
  316.  * by Purple 1.5.0 or older this value will be invalid and
  317.  * very small (close to 0).  This is because Purple 1.5.0
  318.  * and older did not record the timestamp when the status
  319.  * was created.
  320.  *
  321.  * However, this value is guaranteed to be a unique
  322.  * identifier for the given saved status.
  323.  *
  324.  * @param saved_status The saved status.
  325.  *
  326.  * @return The timestamp when this saved status was created.
  327.  */
  328. time_t purple_savedstatus_get_creation_time(const PurpleSavedStatus *saved_status);
  329.  
  330. /**
  331.  * Determine if a given saved status has "substatuses,"
  332.  * or if it is a simple status (the same for all
  333.  * accounts).
  334.  *
  335.  * @param saved_status The saved status.
  336.  *
  337.  * @return TRUE if the saved_status has substatuses.
  338.  *         FALSE otherwise.
  339.  */
  340. gboolean purple_savedstatus_has_substatuses(const PurpleSavedStatus *saved_status);
  341.  
  342. /**
  343.  * Get the substatus for an account in a saved status.
  344.  *
  345.  * @param saved_status The saved status.
  346.  * @param account      The account.
  347.  *
  348.  * @return The PurpleSavedStatusSub for the account, or NULL if
  349.  *         the given account does not have a substatus that
  350.  *         differs from the default status of this PurpleSavedStatus.
  351.  */
  352. PurpleSavedStatusSub *purple_savedstatus_get_substatus(
  353.                                     const PurpleSavedStatus *saved_status,
  354.                                     const PurpleAccount *account);
  355.  
  356. /**
  357.  * Get the status type of a given substatus.
  358.  *
  359.  * @param substatus The substatus.
  360.  *
  361.  * @return The status type.
  362.  */
  363. const PurpleStatusType *purple_savedstatus_substatus_get_type(const PurpleSavedStatusSub *substatus);
  364.  
  365. /**
  366.  * Get the message of a given substatus.
  367.  *
  368.  * @param substatus The substatus.
  369.  *
  370.  * @return The message of the substatus, or NULL if this substatus does
  371.  *         not have a message.
  372.  */
  373. const char *purple_savedstatus_substatus_get_message(const PurpleSavedStatusSub *substatus);
  374.  
  375. /**
  376.  * Sets the statuses for all your accounts to those specified
  377.  * by the given saved_status.  This function calls
  378.  * purple_savedstatus_activate_for_account() for all your accounts.
  379.  *
  380.  * @param saved_status The status you want to set your accounts to.
  381.  */
  382. void purple_savedstatus_activate(PurpleSavedStatus *saved_status);
  383.  
  384. /**
  385.  * Sets the statuses for a given account to those specified
  386.  * by the given saved_status.
  387.  *
  388.  * @param saved_status The status you want to set your accounts to.
  389.  * @param account      The account whose statuses you want to change.
  390.  */
  391. void purple_savedstatus_activate_for_account(const PurpleSavedStatus *saved_status, PurpleAccount *account);
  392.  
  393. /**
  394.  * Get the handle for the status subsystem.
  395.  *
  396.  * @return the handle to the status subsystem
  397.  */
  398. void *purple_savedstatuses_get_handle(void);
  399.  
  400. /**
  401.  * Initializes the status subsystem.
  402.  */
  403. void purple_savedstatuses_init(void);
  404.  
  405. /**
  406.  * Uninitializes the status subsystem.
  407.  */
  408. void purple_savedstatuses_uninit(void);
  409.  
  410. /*@}*/
  411.  
  412. #ifdef __cplusplus
  413. }
  414. #endif
  415.  
  416. #endif /* _PURPLE_SAVEDSTATUSES_H_ */
  417.